MACD 5

home *** CD-ROM | disk | FTP | other *** search

/ MACD 5 / MACD 5.bin / workbench / libs / shadowlib.lha / shadow / Docs / ShadowLibraryFuncs.doc < prev next >

Wrap

Text File | 1992-11-13 | 137KB | 4,374 lines

Shadow.library Documentation Library Version 5.0 By David Navas Updated: 13 Nov 1992 Copyright © 1992 by David Navas All Rights Reserved NAME AddAttributes -- Create the attribute table for a class. SYNOPSIS result = AddAttributes( class, tags, num, offset ) d0 a0 a1 d0 d1 FUNCTION This function creates the array of Attribute structures that are described both by the tags and by the superclass of the passed class. This is a low-level function which is used by the provided Metas. You should not have to call this function yourself, however you can if for some reason you feel compelled to do so. Note that the array of Attributes, as stored in the class' AttributeTable, includes all of the attributes, both as described in the tags, AND as described in the superclass. If you're looking for an attribute description, you don't need to look at any superclass to find it. It is unfortunate that, unlike METHODs, attributes defined in the superclass have to copied to all subclasses. In reality, only the WATCHED attributes NEED to be copied, however this involves an increased level of complexity which has yet to be implemented, and so it remains -- 16bytes per attribute.... sigh. There are some benefits, however. Multiple inheritence of attributes is easy. It's unimplemented, but it's a hop-skip-jump away.... After forming the AttibuteTable, the attributes are qsort'ed by the attribute name, for fast attribute lookup. Note that this is a sorting by the System String's address, not by the string's value. For more information about system Strings, see the UseString() function. INPUTS META class; - the new class for which to build an AttributeTable. Function returns NULL if NULL class is passed. ATTRIBUTE_TAG tags[]; - the (optional) new atributes to include. long num; - the number of additional attributes from the class' superClass -- as returned by PrepareAttrTags(). ULONG offset; - the offset at which the next attribute will reside. This is usually the size of the class' superClass. OUTPUTS long result; - result code (should be a BOOL, oh well.) Specifies whether the AttributeTable was successfully built. NULL indicates an error. RESULT The specified class' AttributeTable is initialized. BUGS none known. NOTES Attributes are guaranteed to be arranged according to the order in which they are specified in the tags[]. This allows you to build a fixed structure over several attributes, or even over the whole object definition. [Internally this is done for all of the classes, with the exception of DIRECTOR_CLASS.] EG: The following: ATTR_1 struct MyAttr1 ATTR_2 struct MyAttr2 ATTR_3 struct MyAttr3 Is basically the same as: ATTR_1 struct { struct MyAttr1 struct MyAttr2 struct MyAttr3 }; SEE ALSO PrepareAttrTags() CopyDefaultAttributes() FreeAttributes() FindAttribute() FindAttrDefn() UseString() NAME AddAutoResource -- Adds an automatically freed resource to a process. SYNOPSIS result = AddAutoResource( task, resource, key) d0 a0 d0 a1 FUNCTION This function adds the specified resource to the optionally specified task (defaults to current task) using the specified key. These resources are kept on the PROCESS_CLASS' ATTR_RESOURCETREE, and are automatically freed (via a METH_REMOVE, and a DropObject()) whenever: a) The process receives a METH_REMOVE b) The process receives a METH_DESTROY c) The process receives a METH_PROC_DISASSOCIATE d) A program inside of RemoveCurrentProgram() receives a ^C e) The default thread-start function inside of SHADOW (after returning from the METH_PROC_HANDLER method) receives a ^C. It is important to note that the resource is TRANSFERRED to (swallowed by) the ATTR_RESOURCETREE. So you no longer own an object pointer to the resource you passed to AddAutoResource(). If this is a problem you can do: AddAutoResource(NULL, UseObject(resource), MYNAME) . . <code referencing resource> . . DropObject(resource) <continue processing, no longer have pointer to resource> . . INPUTS OBJECT task; - The optional task object that performs the auto-tracking. If not specified, assumes current taskObject. OBJECT resource; - The object to auto-track. char *key; - The name of the resource. Resources without names (key == NULL) are stored by their addresses. Name addresses of 0-255 are reserved for priority freeing. Resources are freed in INCREASING key order. Obviously, you can't use AddAutoResource() to add a resource at priority zero, as then the resource would be added at the address of the resource (NULL == 0). OUTPUTS BOOL result; - result code Specifies whether the resource was added correctly. If it was not, the resource is sent a METH_REMOVE, is dropped, and a FALSE value is returned to indicate an error. If the resource was NULL, then this function returns FALSE Otherwise returns TRUE RESULT The resource is now auto-tracked by the indicated process. BUGS none known. NOTES SEE ALSO RemoveAutoResource() DropObject() UseObject() NAME AddClassWatcher -- Adds a watcher to the given class. SYNOPSIS result = AddClassWatcher( watchName, director, pri, name, class ) d0 a0 a1 d2 d0 d1 FUNCTION This function will add the director to the class' attribute's watching SList at the given priority with the given name. This is a low-level function. You should use the provided DIRECTOR_CLASS methods instead and ask specifically for a class watcher. Example is in browser.c -- GlobalDirector.... Or see the inluded ShadowLibraryMethods.doc for more details INPUTS char *watchName; - the attribute name to watch OBJECT director; - the director to add to the attribute watching SList. long pri; - the priority to add the watcher as. char *name; - the name of the watcher. META class; - the class to add the watcher to. OUTPUTS BOOL result; - result code The result code is a boolean indicating the success or failure of the function call. A zero value indicates that an error occured. RESULT The director is added to the class' attribute's watch list. BUGS none known. NOTES SEE ALSO AddWatcherNode() RemoveWatcherNode() RemoveClassWatcher() NAME AddMethods -- initializes a class' method table SYNOPSIS result = AddMethods( class, tags ) d0 a0 a1 FUNCTION This function creates the array of MethodHandler structures that are described both by the tags. This is a low-level function which is used by the provided Metas. You should not have to call this function yourself, however you can if for some reason you feel compelled to do so. Note that the array of MethodHandlers, as stored in the class' MethodTable, includes only those methods described in the tags field. Unlike attributes, the superclass' methods are NOT copied down to the newly defined class. While creating the MethodHandlers, the passed procObject and defnObject are UseObject()'d, ensuring that the destination process and the defining process hang around until the class referencing the methods goes away. After forming the MethodTable, the methods are qsort'ed by the method name, for fast method lookup. Note that this is a sorting by the System String's address, not by the string's value. INPUTS META class; - required class to add the methods to. METHOD_TAG tags[]; - the (optional and NULL-terminated) array of MethodTag elements. OUTPUTS int result; - result code The result code is an integer indicating the success or failure of the function call. A zero value indicates that an error occured. RESULT The class' verbs field is initialized. BUGS none known. NOTES SEE ALSO DSM() DoShadow() [ShadowLibFuncs.doc] InvalidateCache() SetMethodArgs() DestroyMethodTable() FindMethodHandle() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME AddSListNode -- Adds a node to a prioritized singly linked list. SYNOPSIS result = AddSListNode( list, object, pri, name ) d0 a0 a1 d0 d1 FUNCTION This function adds an object into a singly linked list with the given name at the given priority (list is ordered by priority). INPUTS SList *list; - a pointer to the list to which to add the object. OBJECT object; - the object to add. long pri; - the priority char *name; - the name to add it as. OUTPUTS BOOL result; - result code The result code is an integer indicating the success or failure of the function call. A zero value indicates that an error occured. Lists of equal priorities are treated as LIFOs. RESULT The list has one more node on it -- the passed object. BUGS none known. NOTES SEE ALSO FindNodePriInSList() AddWatchedSListNode() RemoveSListNode() RemoveWatchedSListNode() NAME AddTreeNode -- adds an object into binary tree. SYNOPSIS result = AddTreeNode( bt, object, key) d0 a0 a1 d0 FUNCTION This function will add the object into the binary tree sorted on the key provided. The object is Used() by the UseObject() call when successfully placed in the binary tree. Any number of objects may exist in any number of binary trees. There is no restriction on how many trees an object can be placed, nor in how many times an object can reside in a binary tree (as there is with Exec lists). In addition, unlike many AVLTree implementation, objects inserted with the same key are handled correctly. INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. OBJECT object; - the object to add into the tree. ULONG key; - the key value to insert on. OUTPUTS BOOL result; - result code zero on failure. (Couldn't allocate binary node) RESULT Object is added into binary tree. BUGS NOne known. NOTES Uses AVL trees. Do not depend on order of insertion on duplicate keys. (Duplicate keys do work, though.) Remember that the keys are sorted unsigned, not signed. SEE ALSO UseObject() AddTreeStringNode() AddWatchedTreeNode() FindTreeNode() AddWatchedTreeStringNode() FreeTreeAllNodes() RemoveWatchedTreeNode() RecurseTree() RemoveWatchedTreeStringNode() RemoveTreeNode() RemoveTreeStringNode() NAME AddTreeStringNode -- add an object to an AVLTREE keyed on a string. SYNOPSIS result = AddTreeStringNode( bt, object, name ) d0 a0 a1 d1 FUNCTION This function will add the object into the binary tree sorted on the name provided. The object is Used by the UseObject() call when successfully placed in the binary tree. The name uses the UseString and DropString conventions for system strings. The address of that string then determines the order the binary tree is sorted in. It is NOT sorted by the string itself, sorry. INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. OBJECT object; - the object to add into the tree. char *name; - the name to insert on. OUTPUTS BOOL result; - result code zero on failure. (Couldn't allocate binary node, or system string) RESULT The object is added into the binary tree sorted on the address of the system string that is uniquely created on the passed name. BUGS none known. NOTES Yes, the third parameter is d1, not d0 No, the binary tree is not sorted on the actual string, but on the address of the associated system string. SEE ALSO UseObject() DropString()/UseString() AddTreeNode() AddWatchedTreeNode() FindTreeNode() AddWatchedTreeStringNode() FreeTreeAllNodes() RemoveWatchedTreeNode() RecurseTree() RemoveWatchedTreeStringNode() RemoveTreeNode() RemoveTreeStringNode() NAME AddWatchedSListNode -- Adds a node to a watched, prioritized singly- linked list. SYNOPSIS result = AddWatchedSListNode( list, object, pri, name ) d0 a0 a1 d0 d1 FUNCTION This function adds an object into a watched, singly-linked list with the given name at the given priority (list is ordered by priority). If any parties are interested, WatcherDispatch is called with W_INSERT_NODE for the flag paramter. INPUTS W_SLIST list; - a pointer to the list to which to add the object. OBJECT object; - the object to add. long pri; - the priority char *name; - the name to add it as. OUTPUTS BOOL result; - result code The result code is an integer indicating the success or failure of the function call. A zero value indicates that an error occured. RESULT The list has one more node on it -- the passed object. BUGS none known. NOTES SEE ALSO AddSListNode() FindNodePriInSList() RemoveSListNode() RemoveWatchedSListNode() NAME AddWatchedTreeNode -- adds an object into watched binary tree SYNOPSIS result = AddWatchedTreeNode( bt, object, key) d0 a0 a1 d0 FUNCTION This function will add the object into the watched binary tree sorted on the key provided. The object is Used() by the UseObject() call when successfully placed in the binary tree. Any number of objects may exist in any number of binary trees. There is no restriction on how many trees an object can be placed (as there is on Exec lists). If any parties are interested, WatcherDispatch is called with W_INSERT_NODE for the flag parameter. INPUTS W_AVLTREE bt; - a pointer to the root of the watched binary tree. OBJECT object; - the object to add into the tree. ULONG key; - the key value to insert on. OUTPUTS BOOL result; - result code zero on failure. (Couldn't allocate binary node) RESULT Object is added into binary tree. BUGS none known. NOTES Uses AVL trees. Do not depend on order of insertion on duplicate keys. (Duplicate keys do work, though.) Remember that the keys are sorted unsigned, not signed. SEE ALSO UseObject() AddTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() FreeTreeAllNodes() RecurseTree() RemoveTreeNode() RemoveWatchedTreeNode() RemoveTreeStringNode() RemoveWatchedTreeStringNode() NAME AddWatchedTreeStringNode -- add an object to a watched AVLTREE, keyed on a string. SYNOPSIS result = AddWatchedTreeStringNode( bt, object, name ) d0 a0 a1 d0 FUNCTION This function will add the object into the watched binary tree sorted on the name provided. The object is Used by the UseObject() call when successfully placed in the binary tree. The name uses the UseString and DropString conventions for system strings. The address of that string then determines the order the binary tree is sorted in. It is NOT sorted by the string itself, sorry. If any parties are interested, WatcherDispatch is called with W_INSERT_NODE for the flag parameter. INPUTS W_AVLTREE bt; - a pointer to the root of the watched binary tree. OBJECT object; - the object to add into the tree. char *name; - the name to insert on. OUTPUTS BOOL result; - result code zero on failure. (Couldn't allocate binary node, or system string) RESULT The object is added into the binary tree sorted on the address of the system string that is uniquely created on the passed name. BUGS none known. NOTES No, the binary tree is not sorted on the actual string, but on the address of the associated system string. SEE ALSO UseObject() DropString()/UseString() AddTreeNode() AddWatchedTreeNode() AddWatchedTreeStringNode() FindTreeNode() FreeTreeAllNodes() RecurseTree() RemoveTreeNode() RemoveWatchedTreeNode() RemoveTreeStringNode() RemoveWatchedTreeStringNode() NAME AddWatcherNode -- Adds a watcher to the watched variable SYNOPSIS result = AddWatcherNode( wv, node, pri, name ) d0 a0 a1 d0 d1 FUNCTION This function will add a watcher object (sometimes referred to as a 'director') into the WatchedVariable wv. This is a low-level routine. You should use the provided DIRECTOR_CLASS method. See browser.c for some examples, or the included ShadowLibMethods.doc for more details. If any parties are interested, WatcherDispatch is called with W_INSERT_WATCHER for the flag parameter. INPUTS W_VALUE wv; - the watched variable to watch OBJECT node; - the director to add to the watch list. long pri; - the priority to add the watcher as. char *name; - the name of the watcher. OUTPUTS BOOL result; - result code The result code is a boolean indicating the success or failure of the function call. A zero value indicates that an error occured. RESULT The director is added to the watch list. BUGS none known. NOTES SEE ALSO RemoveWatcherNode() AddClassWatcher() RemoveClassWatcher() NAME AllocateItem -- Allocates an item from a MemoryList SYNOPSIS element = AllocateItem( list ) d0 a0 FUNCTION Allocates an element from the list. The element will NOT be zeroed out, and may contain data from the last time that element was used. Elements are allocated 32 at a time via the allocfunc() that was passed to the InitTable() function. AllocateItem() doles out these elements one by one, automatically calling allocfunc() when necessary (ie: when it needs another 32 elements because it has no more free elements). INPUTS SEMLIST list; - the list to allocate from. OUTPUTS void *element; - element that is allocated. As with any allocation function, this function can return NULL for a failure to allocate memory. RESULT One item is allocated on the Memorylist BUGS none known. NOTES The memory returned is NOT zeroed. SEE ALSO InitTable() FreeTable() FreeItem() NAME BindSuperWatchers -- copies all watchers on the superClass' watched attributes to the subclass. SYNOPSIS result = BindSuperWatchers( class ) d0 a0 FUNCTION This function is called internally during METH_INIT of all classes and metas. A search is done on the immediate superClass' attributes. Any watchers found on the class' attribute list are copied to the passed class' attribute. Thus, if a new class subclassed off of WindowClass was created while running browser, the watcher that was watching all of the window classes will watch that new window class as well. INPUTS META class; - the (sub)class to bind the watchers. OUTPUTS BOOL result; - the result code. FALSE indicates failure to copy all the watchers. Probably ran out of memory allocating list nodes. RESULT The class' watched variables can now send out notification to the old class watchers for any new objects that are created and stored there, or for any changes in value made to the watched variable. BUGS none known. NOTES SEE ALSO BindWatchers() AddWatcherNode() AddClassWatcher() WatcherDispatch() NAME BindWatchers -- binds all object's attributes' watched wv_firstClass to the appropriate spot in the object's class. SYNOPSIS BindWatchers( object ) a0 FUNCTION This function is called internally during METH_INIT of all objects. It sets all watched variables in the object to have their wv_firstClass pointer pointing to the class' attributes' SList, like it is supposed to. This allows notification of any changes to the watched variable to be sent out on a class basis -- any object of the class will attempt to send notification to both the specific object, and the associated class. An example is in browser.c which is notified whenever any object is added to the ATTR_GUICHILDREN of any object whose class is a descendent of WindowClass. INPUTS OBJECT object; - the object to bind the watchers. OUTPUTS RESULT The object's watched variables can now send out notification to the class watchers. BUGS none known. NOTES SEE ALSO BindSuperWatchers() AddWatcherNode() AddClassWatcher() WatcherDispatch() NAME BlockMethod -- [un]blocks via a METH_FLAG_PREBLOCK, the method in a given class. SYNOPSIS BlockMethod( class, name, pri, block ) a0 a1 d0 d1 FUNCTION This function will search the class for a method of the given name. If pri is non-zero, the patched verbs list of the class is searched for a method patch of the given name and priority. This handle is then either PRE_BLOCK'd or un-PRE_BLOCK'd, according to the block flag. INPUTS META class; - the class where the method is found. char *name; - the name of the method to [un]block. WORD pri; - the priority (or nearest priority) of where the block should take effect. If pri is non-zero, a patch of that pri must exist. WORD block; - whether to block (TRUE) or to unblock (FALSE) OUTPUTS none RESULT A method may be [un]blocked. BUGS none known. Not yet tested! (07 Oct 1992) NOTES SEE ALSO DSM() DoShadow() InvalidateCache() SetMethodArgs() AddMethods() DestroyMethodTable() FindMethodHandle() RemoveAllPatches() SetupMethodTags() NAME ChangeWatchedValue -- Changes a watched variable's value. SYNOPSIS ChangeWatchedValue( wv, new ) a0 d0 FUNCTION Changes the watched variable to the passed new value. If any parties are interested, WatcherDispatch is called with either W_CHANGE_ZERO or W_CHANGE_NON_ZEROin the flag parameter. INPUTS W_VALUE wv; - a watched variable to change. long new; - the value to change to. OUTPUTS RESULT The value is changed, and all parties notified. BUGS none known. NOTES SEE ALSO WatcherDispatch() NAME CopyDefaultAttributes -- Copy the default attrs into the instance SYNOPSIS CopyDefaultAttributes( object ) a0 FUNCTION This function will copy the default values, specified in the object's class, into the object. It is executed by both MetaClass and MetaCluster, and by both rootClass and rootCluster in the METH_CREATE method. It assumes the object is already filled with ZEROs. INPUTS OBJECT object; - The object whose attributes should be initialized. OUTPUTS none RESULT The object's attributes are initialized to the attribute default values stored in the object's class. Object is assumed to have already been initialized to ZEROs. BUGS none known. NOTES object is a required parameter. SEE ALSO PrepareAttrTags() AddAttributes() FreeAttributes() FindAttribute() FindAttrDefn() NAME CreateMeta -- Creates a self-referencing class description. SYNOPSIS meta = CreateMeta( description ) d0 a0 FUNCTION This function creates a Meta. A Meta is a class whose class is itself. Metas are useful for describing Classes and such. The current system creates two Metas: MetaClass and MetaCluster. The description is used to create the Meta using the attributes and superClass pointers. The superClass field, the attribute table and the method table are all filled in. The name is NOT, nor is any other information in the description touched. The passed description's object and class pointers are set up as the allocated meta, the method is initialized either to METH_INIT (if the passed description's method as NULL) or left as passed (if not NULL). CreateMeta then returns "DSM(INVOKE_FIND_SELECTOR, description)". This implies several things: You can create meta structures that need initialization by passing the appropriate arguments in the InitMeta structure. See the InitMeta structure for more details. Your METH_INIT methods should, then, -do-the-right-thing- when passed its own meta, rather than a proper instance of that meta. The correct method for checking for such an event is to compare 'object' with 'object->cob_class' as in: MyMethod(METHOD_ARGS, MYMETHODARGS) { if (object == object->cob_class) { /* * we were passed a meta, so * do what we needed to do with that. */ } else { /* * We were passed a proper instance, so do * what is necessary here. */ } } Specifically, you should NOT do a comparison between 'object' and 'class'. Class can change if called as a superclass method. The object might still be a meta, just not THAT method's meta.... As always, the following methods should also handle being sent a Meta: METH_DESTROY, METH_REMOVE. METH_SUB should also handle Metas by filling in the superClass pointer and passing the arguments to CreateMeta. The following code segment may be useful: MethodMetaSub(METHOD_ARGS, name, superClass, attrList, verbList) { if (!superClass) superClass = object; if (object == object->cob_class) { struct InitMeta *im; im = (struct InitMeta *)&object; im->im_object = im->im_class = NULL; im->im_method = NULL; im->im_super = superClass; return CreateMeta(im); } . . . } A consequence of using METH_SUB to create new Metas is that the initialization parameters are truncated to match the METH_SUB parameter description, which might not pass all the required parameters into the InitMeta structure sent to CreateMeta! Please remember what you are doing. The description structure that is passed is a fixed length header with a variable length number of additional arguments (which should match the initialization routine CreateMeta calls: either the contents of description->im_method OR METH_INIT if that is NULL). As a result, this argument list MUST be terminated by a METHOD_END. Note that all method invocations have a METHOD_END located one argument passed their last defined argument, thus allowing the above code to work properly. Your initialization routine is responsible for setting the Meta's name and adding the meta to ShadowBase->sb_metaTree. However, it should specifically NOT setup the attribute tables and method tables (like it would in the case of a new class) as CreateMeta has already done that for you. The instances of Metas have, likewise, the same attributes as the Meta (as part of their instance, where the Metas have those attributes in both the INSTANCE and in their attribute description table). Reminder: the METH_REMOVE of the meta must distinguish between the case where the passed object != meta (meaning the object is an instance of Meta, and so should be removed from the ATTR_INSTANCETREE of the object->cob_class) and the case where object == meta (meaning the object *is* the meta, and should be removed from the system's metaTree -- &ShadowBase->sb_metaTree). Similarly for METH_DESTROY -- don't drop the object's cob_class when you destroy the meta ie: object == object->cob_class), and do transfer the class: if (object == class) IpcARGTransfer(msg, 1); INPUTS struct InitMeta *im; - the initialization description. See includes OUTPUTS META meta; - the meta that was created. NULL if error. RESULT BUGS none known. NOTES SEE ALSO UseObject() DropObject() FindInstanceOfMeta() NAME CreateObject -- creates an object with the same data as the ptr. SYNOPSIS object = CreateObject( ptr, size ) d0 a0 d0 FUNCTION This function creates a ClasslessObject, which can be UseObject()'d and DropObject()'d at will, whose included data is the data located in ptr, covering "size" bytes. If given both a non-NULL pointer and non-zero size, it allocates an object of sizeof(struct ClasslessObject)+size and sets up the fields according to what a ClasslessObject should look like: clb_size = size; clb_useCount = 1; clb_class = NULL; As noted, the returned object is Use'd once, so it should be DropObject()'d when its life expires. INPUTS void *ptr; - the object to effect the change upon. ULONG size; - the size of the data pointed to by ptr. OUTPUTS OBJECT object; - the allocated object with the (optional) passed data. NULL if error. RESULT A new ClasslessObject is created. BUGS none known. NOTES SEE ALSO UseObject() DropObject() NAME DestroyMethodTable -- frees the array of methods. SYNOPSIS DestroyMethodTable( table ) a0 FUNCTION This function will destroy the MethodTable's array of MethodHandlers (usually the class' meta_verbs field). It resource-tracks the procObject, defnObject, and method names in the MethodHandler elements. At this point, the routine will DropObject() or DropIPCPort() or DropString() these fields. INPUTS struct MethodTable *table; - required parameter. Usually found in class->meta_verbs. OUTPUTS RESULT The array, if a non-NULL ptr, is freed. BUGS none known. NOTES SEE ALSO DSM() DoShadow() InvalidateCache() SetMethodArgs() AddMethods() FindMethodHandle() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME DropObject -- resource tracking for shadow objects. SYNOPSIS DropObject( object ) a0 FUNCTION This function decrements the object's cob_useCount. You should Drop() an object when you free a structure that had a pointer-to-object in it. In addition, certain method calls, like METH_INIT return an object to you. When you are done using the pointer, you are expected to drop the pointer. A word about self-referencing. Self-referncing is an evil problem in useCount systems. You should DropObject() all self-references during the METH_REMOVE call of an object. For instance, if your class maintained a binary tree of gadget objects, and these gadget objects pointed back to the window object, the IDCMP_WINDOWCLOSE should do a METH_REMOVE on the window, which in turn should METH_REMOVE it's gadgets, and those gadgets should remove all references to the window object during that METH_REMOVE call. If the useCount of the object drops to zero furing DropObject(), the object's destructor (METH_DESTROY) is called. If the object in question has no class, than it is assumed to be a ClasslessObject, and the clb_size is looked at. If this field is non-zero, the object is freed, with "FreeMem(object, object->clb_size);" You must be careful when designing asynchronous METH_DESTROY methods -- please see IpcItemTransfer() for further details. INPUTS OBJECT object; - the object to effect the change upon. OUTPUTS RESULT BUGS none known. NOTES SEE ALSO UseObject() IpcItemTransfer() Introduction.doc :: resource tracking NAME DropString -- Removes a reference to a system string. SYNOPSIS DropString( buffer ) a2 FUNCTION This function searches the system string list for the system string corresponding to the passed buffer, then decrements the internal usage counter for that system string by one. If the counter becomes zero, that system string is freed from memory. If no string can be found to match buffer, no action is taken. INPUTS char *buffer; - equivalent string to the system string that you want the system to drop a reference to. OUTPUTS RESULT The system string corresponding to the passed buffer has one fewer references to it. BUGS none known. NOTES The buffer should be word-aligned for faster access. long-word aligned is preferred. SEE ALSO UseString() QuickUseString() FindString() QuickDropString() NAME DSM -- parses out the requested method, calls and/or sends out the appropriate function(s)/message(s) SYNOPSIS result = DSM(flags, arguments ) d0 d1 a1 FUNCTION This function is the work horse of the entire system. It is responsible for sending off all METHODs, whether synchronously, asynchronously, or as a function call. In addition, it also sends off all method patches as requested. DSM() takes a number of flags which are found in <shadow/message.h>. They are meant to override similar flags which are located in the METHOD_TAG definition of each individual method. Following is their meaning: INVOKE_CALL - DEFAULT assumption -- calls method as function unless specified otherwise in the METHOD_TAG INVOKE_SYNC - Overrides the method's mtag_threadstat field. The method is sent as a synchronous message to the method's destination process [usually mtag_procObject; see: SetupMethodTags and INVOKE_WITH_PROCESS], unless the calling process belongs to a superset (non-proper) of the destination's process, in which case the method is called as a function. INVOKE_ASYNC - Overrides the method's mtag_threadstat field. The method is sent as an asynchronous message to the method's destination process [usually mtag_procObject; see: SetupMethodTags and INVOKE_WITH_PROCESS], unless the calling process belongs to a superset (non-proper) of the destination's process, in which case the method is called as a function. INVOKE_FORCE - Used in onjunction with above flags. See next three flags. INVOKE_FORCE_SYNC - Overrides the method's mtag_threadstat field. The method is sent as a synchronous message unless the calling process is exactly equivalent to the destination process, in which case the method is called as a funcion. INVOKE_FORCE_ASYNC- Overrides the method's mtag_threadstat field. The method is ALWAYS sent as an asynchronous message. Irregardless of calling/destination process. INVOKE_FORCE_CALL - This is used to override the method's mtag_threadstat and force a function call equivalent. INVOKE_WITH_PROCESS-This indicates that the passed argument array has a preceding process object which should be used as the destination process for the method. The process will only be used providing that it is required by the method (ie: that the method is called synchronously or asynchronously and meets the requirements of the calling/destination process as described in the INVOKE_[FORCE_][A]SYNC flags above), AND if the INVOKE_IGNORE_PROCESS flag is not set in the mtag_threadstat field of the method. The INVOKE_IGNORE_PROCESS is the exact equivalent of the INVOKE_WITH_PROCESS. However, because of the difference in both meaning and placement, the INVOKE_WITH_PROCESS flag name should be used with DSM(), and the INVOKE_IGNORE_PROCESS should be used with the mtag_threadstat. INVOKE_FROM_SUPER - This flag indicates the wish to call a passed class' superclass. The second field of the arguments will be -modified- by DSM() to the class' superclass, and the method then invoked normally. Additional doMethod function callback checking will occur -- both for the original class and the superclass. INVOKE_FIND_SELECTOR - The selector is looked up in the system's hashtable of strings using the FindString() SHADOW library call. The address of this system string is used to select the method to call. INVOKE_RETURN_MSG - The DSM() call returns a message which can be used to later generate the actual method as specified in the passed arguments. All resource tracking on the arguments is done within DSM(). The returned message can be junk()'d with the JunkIPCMessage() SHADOW library call, or the method can be sent as an argument to another function, and in that method you can call the ParseShadowMessage() to call the method associated with the message. Please see the examples in ShadowLibFuncs.doc under the PreParseShadow() .lib function. If the "flags" argument specifies that the methods should be forced to send all methods INVOKE_ASYNC or INVOKE_FORCE_ASYNC, then a single message is sent to the primary handle's procObject asynchronously with the function callback set back to DSM. When DSM() is then called by the other proces (the message having been parsed out by MessageParse(), usually handled by ParseShadowMessage()), the method and all of its patches are sent out without the INVOKE_ASYNC specification. This corrects the case where a patch is supposed to be able to -synchronously- control any subsequent patches (METH_FLAG_CHECK_CONTINUE). Obviously if all methods and all patches were sent out asynchronously, there would be no chance for a synchronous-type behaviour to act correctly. Therefore, the initial send is asynchronous to the caller, but the complete method handling, including synchronous calling of patches, occurs synchronously to the called process. Consequently, if the method itself (as represented in its METHOD_TAG description) is flagged with INVOKE_FORCE_ASYNC, and DSM() is called with the INVOKE_ASYNC flag, then there are actually -two- messages that are sent. One is the message described above which handles the synchronous patch-handling asynchronously to the calling process, the other message occurs when the method is processed in the called task -- the method was created as being invoked asynchronously, independently from where it is called, so another message is sent back to the same process! Representing the method as INVOKE_ASYNC, as opposed to INVOKE_FORCE_ASYNC, will avoid this problem, although in this case you may not be able to make the process asynchronous enough to avoid the cases where synchronous behaviour is unwanted. The best way to avoid these problems is to use the INVOKE_FORCE_ASYNC flag in METHOD_TAGs as little as possible, and only call DSM() with the asynchronous flag as needed. The .lib functions DoShadowAsync(), DoShadowInProcessAsync(), etc. all call DSM() with the INVOKE_ASYNC bit set. If you cannot avoid these issues, you may want to consider creating your own process class for the method, allowing, therefore, an INVOKE_ASYNC bit to correctly be asynchronous to every process -except- when called from within this "double-nested" DSM(). In that case, because the calling process and the method-destination process are equivalent, the method is invoked via the function, and not another message. There is more overhead in creating your own process class (an extra CreateSubClass() call), but it may be worth your trouble.... In addition to these passed flags, many of the mtag_flags located in the method description are used to enhance DSM()'s capabilities of sending methods across process boundaries. These flags can be found in <shadow/misc.h>: METH_FLAG_OBJECT - The mtag_procObject is interpreted as the destination process. METH_FLAG_PORT - The mtag_procObject is interpreted as an IPCPort to which method-messages are sent. METH_FLAG_CLASS - The mtag_procObject is interprted as a class of process objects. This class is instantiated, and the resulting process object is used as the destination for that particular invocation. METH_FLAG_OBJECT_AS_DEST - The object inside of the passed arguments (ie: *(OBJECT *)arguments) is considered the destination for the method. This is particularly useful for process methods which must (for reasons of port allocation or other Signal-bit allocation, etc.) be run in the process with which the process-object corresponds. METH_FLAG_SPEC - The mtag_procObject is interpreted as a pointer to a struct MethInvokeSpec [see: <shadow/method.h>], the complete meaning of which depends on the above four flags in the following manner: METH_FLAG_SPEC | METH_FLAG_OBJECT mis_instanceName is the name of the process object to use as the destination object. mis_className is the class name of the class of the above process object. mis_metaName is the meta's name of the meta of the above class. Usually this is META_CLASS. METH_FLAG_SPEC | METH_FLAG_PORT mis_instanceName is the name of the IPCPort to use as the destination port. This port will NOT be created, but must exist when the method is called. mis_className is NULL mis_metaName is NULL METH_FLAG_SPEC | METH_FLAG_CLASS mis_instanceName is NULL mis_className is the class name of the process to create. mis_metName is the meta's name of the meta of the above class. Usually this is META_CLASS. METH_FLAG_SPEC | METH_FLAG_OBJECT_AS_DEST the METH_FLAG_SPEC is meaningless in this case as the METH_FLAG_OBJECT_AS_DEST never uses the mtag_procObject field. When the process/port is looked-up/created, the process/port may replace the MethInvokeSpec structure, eliminating the need to lookup the object/class/port again. To do this, set the SPEC_SAVE_BINDING flag in the mis_flags field of the MethInvokeSpec structure. The following METH_FLAGs are passed in at method or patch creation in the MethodTag mtag_flags field: METH_FLAG_[POST|PRE]_BLOCK - ends the sending of methods off as DSM() works from the highest priority patch, to the normal MethodHandle, to the lowest priority patch. POST_BLOCK ends the method chain after -that- method in the patch-chain is sent off, PRE_BLOCK ends it BEFORE that method is sent off. METH_FLAG_NO_RTRN - informs DSM() that a patch or method has no return value. By default, all methods and patches have return values. Note that this is a change from SHADOW 4! METH_FLAG_CHECK_CONTINUE - checks the return value returned in d1 (that's d1, not d0). If d1 is TRUE, then the method-chain is continued, if FALSE (zero), then the method chain ends at that point. A method-chain exists whenever a method is patched. These patches are called from high priority to zero, when the regular handle is called, and then lower priority patches are called. This chain of method calls can be terminated by the *_BLOCK or CHECK_CONTINUE flags mentioned above. Patches are discussed in more detail in both the ShadowLibraryMethods.doc and the Introduction.doc. Thus, we have a picture of DSM(). First, the doMethod() callback of the passed class is checked to see if someone else wants to process the method calls (see NOTE: below). Then , if necessary, the superclass is loaded and the same doMethod() check is made. The selector is rendered into a legal system selector, and the method found in the class or class hierarchy. The method is then checked to see if it's merely a function call, or a series of function/[a]synchronous calls in a patch-chain. If the former, the method is invoked, if the latter, a series of actions are taken to invoke the method correctly, whether as a function call (as an INVOKE_[A]SYNC might turn out to be), or as a message of some kind, or as a series of function calls and message sends. To avoid headaches, just use the Do*Shadow*() calls in the .lib instead.... INPUTS void **arguments; - a pointer to the arguments. First should be the object, then a valid class, then a method, then the rest of the arguments according to the ArgumentTag structure, ending with a METHOD_END (0x80000001) ULONG flags; - if low byte non-zero, treat as a specification for the type of method to send (INVOKE_CALL, etc.). A INVOKE_FORCE alone specifies that the method should be called. The flag affects any method patches as well. INVOKE_SUPER indicates the method should be sent to the superclass of the class as poassed in arguments[1]. INVOKE_FIND_METHOD indicates that the method needs to be lookup up in the systemString via the FindString call. OUTPUTS void *result; - result from method parse. RESULT BUGS none known. NOTES DSM() caches methods for faster lookups (a bit less than thrice as fast in worst case function calls). DSM() checks the class' doMethod function callback both BEFORE and AFTER any INVOKE_SUPER handling. This callback should act like DSM(), if you want to change the way DSM() works. The callback does, however, take its parameters in d0/a0 not d1/a1. The callback is located in the class structure -- inside of the struct CoreClass, to be exact [<shadow/coreMeta.h>]. As DSM() searches up the class hierarchy for the method, each class' doMethod() callback is checked. if it exists, the function is then called. Use the Do*Shadow*() method calls instead! SEE ALSO Do*Shadow*() InvalidateCache() SetMethodArgs() AddMethods() DestroyMethodTable() FindMethodHandle() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME FindAttrDefn -- Finds the attribute structure in the class SYNOPSIS attribute = FindAttrDefn( class, name ) d0 a0 a1 FUNCTION This function finds the Attribute structure (the element in the class' array) of the specified class. If the class has a callback attribute function, that function is called instead. Otherwise, the array is radix searched for the attribute whose name corresponds to FindString(name). INPUTS META class; - the class whose attribute is wanted returns NULL for a NULL class. char *name; - the name of the attribute to find. OUTPUTS struct Attribute *attribute; - pointer to the Attribute structure as specified in the class. RESULT BUGS none known. NOTES The attribute callback function is called: ccl_attrDefnFunc() and is located in the struct CoreClass described in <shadow/coreMeta.h>. SEE ALSO PrepareAttrTags() FindString() AddAttributes() CopyDefaultAttributes() FreeAttributes() FindAttribute() NAME FindAttribute -- Finds the instance of the attribute in the object SYNOPSIS attribute = FindAttribute( object, name ) d0 a0 a1 FUNCTION This function will find the specified structure inside of the object and return the address of that structure. Calls FindAttrDefn() on the object's class. INPUTS OBJECT object; - the object whose attribute is wanted. returns NULL for a NULL object, or an object with a NULL class. char *name; - the name of the attribute to find. OUTPUTS void *attribute; - pointer to the object's attribute. This pointer points to the insides of an object. RESULT BUGS none known. NOTES Calls FindAttrDefn internally. SEE ALSO PrepareAttrTags() AddAttributes() CopyDefaultAttributes() FreeAttributes() FindAttrDefn() NAME FindInstanceOfMeta -- Bi-level search for instances of a Meta (Classes!) SYNOPSIS class = FindInstanceOfMeta( className, metaName ) d0 a0 a1 FUNCTION This function is useful for finding a Class. A Class always resides in the ATTR_INSTANCETREE of its defining Meta (until removed via the METH_REMOVE method). The Metas all reside in ShadowBase->sb_metaTree. Therefore, it takes two FindWatchedTreeStringNode() calls to find a class (or Cluster). This is how FindShadowClass() and FindShadowCluster() are #defined.... INPUTS char *className; - the name of the class you are looking for. char *metaName; - the name of the Meta that the class is in. OUTPUTS OBJECT class; - the pointer to the class. NULL if can't find. RESULT BUGS none known. NOTES You should DropObject() the class when you are finished using it. SEE ALSO UseObject() DropObject() CreateMeta() FindNamedObject() NAME FindMethodHandle -- finds the associated handle in the class. SYNOPSIS handle = FindMethodHandle( class, method ) d0 a0 a1 FUNCTION This function will search the class' verb table for the required method. It does not look in any superclasses to find it. INPUTS META class; - the (optional) class in which to find the method. char *method; - the name of the method to look for. MUST be the system string equivalent (you can get this from the FindString() function. OUTPUTS struct MethodHandle *handle; - the returned handle. NULL if not found. RESULT BUGS none known. NOTES SEE ALSO DSM() DoShadow() InvalidateCache() SetMethodArgs() AddMethods() DestroyMethodTable() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME FindNamedObject -- Tri-level search for instances of a Class of a Meta SYNOPSIS object = FindNamedObject( instanceName, className, metaName ) d0 d0 a0 a1 FUNCTION This function is useful for finding a named OBJECT like a process. A Process' Class always resides in the ATTR_INSTANCETREE of its defining Meta (until removed via the METH_REMOVE method). Likewise, the process OBJECT always resides in the ATTR_INSTANCETREE of its defining process class. Therefore, it takes three FindWatchedTreeStrngNode() calls to find a named object. INPUTS char *instanceName; - the name of the object we're looking for. char *className ; - the name of the class you are looking for. char *metaName ; - the name of the Meta that the class is in. OUTPUTS OBJECT object ; - the pointer to the object. NULL if can't find. RESULT BUGS none known. NOTES You should DropObject() this object when you are finished using it. SEE ALSO UseObject() DropObject() CreateMeta() FindInstanceOfMeta() NAME FindNodePriInSList -- Finds an object in the singly linked list SYNOPSIS object = FindNodePriInSList( list, pri, name ) d0 a0 d0 a1 FUNCTION This function finds an object in a singly linked list with the given name at the given priority (list is ordered by priority). INPUTS SList *list; - a pointer to the list in which to find the object. long pri; - the priority char *name; - the name it was added as. OUTPUTS OBJECT object; - the object, if found. NULL otherwise. RESULT BUGS none known. NOTES The found object is UseObject()'d, please DropObject() it when you are finished using the pointer. SEE ALSO AddSListNode() AddWatchedSListNode() RemoveSListNode() RemoveWatchedSListNode() UseObject() DropObject() NAME FindString -- Find a system string SYNOPSIS string = FindString( buffer ) d0 a2 FUNCTION This function hashes the buffer string and searches on the collision binary tree for any matches. It will return the system string, if it finds it. It will NOT increment the internal useCount, so you should not use what is returned as either a system string, nor even as a string, but merely as an address you are searching a table for -- and even then, you must be careful of race conditions, the address should remain valid for the entire time you are searching a table or structure, or the table/structure must be locked in memory during the time you look up the string and the time you are searching the table. INPUTS char *buffer; - the buffer whose system string you want to find. Given a NULL, will return a NULL OUTPUTS char *string; - the string, if found. NULL if no string. RESULT BUGS none known. NOTES The buffer should be word-aligned for fast access and long-word aligned for fastest access. SEE ALSO UseString() QuickUseString() DropString() QuickDropString(); NAME FindTreeNode -- Finds the object in the binary tree SYNOPSIS object = FindTreeNode( bt, key ) d0 a0 d0 FUNCTION This function returns the first object in the binary tree that matched the key passed to the function. Note that a corollary function FindTreeStringNode() is usually defined as FindTreeNode(bt, FindString(name)). The object is Used() via the UseObject() call. When the pointer that is returned is no longer needed, it should be Drop()'d via the DropObject() call. INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. ULONG key; - the key to look for. OUTPUTS OBJECT object; - the object that is found NULL is returned if no object is found. RESULT The node is located in the binary tree. BUGS none known. NOTES Please DropObject() any objects returned when no longer needed. Remember that the keys are sorted unsigned, not signed. SEE ALSO UseObject()/DropObject() AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FreeTreeAllNodes() RemoveWatchedTreeNode() RecurseTree() RemoveWatchedTreeStringNode() RemoveTreeNode() RemoveTreeStringNode() NAME FreeTreeAllNodes -- Frees all nodes in a particular binary tree SYNOPSIS FreeTreeAllNodes( bt ) a0 FUNCTION This function will remove all nodes off of the binary tree, dropping all objects, and all strings. The binary tree is assumed to contain objects sorted on a string as a key. Please do not call it on any other type of binary tree, as it would be dropping potentially non-existant string objects. V4.2 UPDATE! You may now call it with a binary tree that is sorted on keys identical to the pointer to the objects each node holds. ie: keys added with: AddTreeNode(&bt, object, object); -or- with keys of less than 256, which are assumed to be merely longwords and not pointers to strings.... INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. OUTPUTS RESULT bt is now a pointer to an empty binary tree. BUGS none known. NOTES Don't call this function on a binary tree sorted by keys that aren't system strings, aren't less than 256 and aren't equal to the corresponding object. SEE ALSO AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() RemoveWatchedTreeNode() RecurseTree() RemoveWatchedTreeStringNode() RemoveTreeNode() RemoveTreeStringNode() NAME FreeAttributes -- Frees all Attribute structures for the class SYNOPSIS FreeAttributes( table ) a0 FUNCTION This function will free the array of Attributes in the AttributeTable. Called during METH_DESTROY for classes and metas. INPUTS struct AttributeTable *table; - pointer to the attribute table to free. Probably a pointer into a class that is going away. OUTPUTS none RESULT The memory allocated in that table is freed. The Table structure itself is NOT freed. BUGS Should probably be called DestroyAttributeTable() NOTES table is a required parameter This is a system function, and probably not something that you will need to call. SEE ALSO PrepareAttrTags() AddAttributes() CopyDefaultAttributes() FindAttribute() FindAttrDefn() NAME FreeClassWatchers -- frees all the watchers in the class' attributes SYNOPSIS FreeClassWatchers( class ) a0 FUNCTION This function frees all watchers left on any of the class' attribute-watching SLists. INPUTS META class; - the class whose attributes' watchers need to be removed. OUTPUTS RESULT All watchers in a class are removed. BUGS none known. NOTES For some reason, class watchers need to be removed from the class when the class is removed. Therefore, the METH_REMOVE for metas and roots calls this function. SEE ALSO FreeObjectWatchers() AddClassWatcher() NAME FreeItem -- Frees an element belonging to a MemoryList SYNOPSIS FreeItem( list, ptr ) a0 a1 FUNCTION This function frees an element that was allocated via the AllocateItem() function. The element may, or may not, be returned to Exec's free memory pool, but may, thereafter, be re-used by AllocateItem() for some other program. INPUTS SEMLIST list; - the MemoryList the element belongs to. void *ptr; - the element pointer OUTPUTS RESULT The element is returned to be re-used by AllocateItem for the specified MemoryList. BUGS Infinite loop occurs if ptr was not on the MemoryList to begin with. NOTES The MemoryList passed MUST be the MemoryList from which the element was allocated. SEE ALSO InitTable() AllocateItem() FreeTable() NAME FreeObjectWatchers -- frees all the watchers in the object's vars. SYNOPSIS FreeObjectWatchers( object ) a0 FUNCTION This function removes all watchers from all variables in the object. INPUTS OBJECT object; - the object whose watched variables need to be removed. OUTPUTS RESULT All watchers of all watched variables in the object are removed. BUGS none known. NOTES This function, as opposed to FreeClassWatchers(), can be called in the METH_DESTROY. The Metas and Roots currently call this function. SEE ALSO FreeClassWatchers() AddClassWatcher() NAME FreeTable -- free all the memory nodes on the MemoryList SYNOPSIS FreeTable( list ) a0 FUNCTION This function frees all resources that the MemoryList acquired during run-time. This means that any outstanding MemoryNodes are thereafter freed -- and therefore not usable to whomever may own them. No attempt is made to ensure all items have been released before all outstanding MemoryNodes are freed by the freefunc() originally passed to InitTable. FreeItem automatically frees MemoryNodes when it "feels" there are plenty of free elements available for use. However, that means that even when all elements are FreeItem()'d, there will still be many MemoryNodes on the MemoryList. This function will free those remaining MemoryNodes. INPUTS SEMLIST *list; - the MemoryList to purge. OUTPUTS RESULT The MemoryList no longer contains any outstanding resources. BUGS none known. NOTES The notion of '"feels" there are plenty of free elements' is intentionally vague. SEE ALSO InitTable() AllocateItem() FreeItem() NAME GetObject -- Semaphored access to an object in a public area. SYNOPSIS object = GetObject(objectPtr ) d0 a1 FUNCTION In some attributes, there may be object pointers that you need to retrieve from that attribute. On the other hand, somebody else might change it at the same time. This function uses the ShadowBase->sb_semSemaphore to protect the access to the objectPtr. The object that is returned is returned Use()'d, so when you are done with the object you should call DropObject(object) on it. INPUTS OBJECT *objectPtr; - the pointer to the structure element that holds the object pointer you want. OUTPUTS void *object; - the object that *objectPtr points to. RESULT object returned is UseObject()d once. BUGS none known. NOTES SEE ALSO RemoveObject() SetObject() NAME GetShadowError -- Get an error code from SHADOW SYNOPSIS result = GetShadowError() d0/d1 FUNCTION This function retrieves the last SHADOW error and suberror that occurred within the calling process' context. This is useful to use when you need to differentiate between a failure to send a message, and an asynchronous send which ALWAYS returns a NULL, or a successful, but NULL-returning, method. You should ClearShadowError() first, of course.... /* * The following is included for clarity, but is actually * present in the shadow_proto.h include file. */ #define ClearShadowError() SetShadowError(0,0); . . . union { double tempD; ULONG tempV[2]; } retval; ClearShadowError() if (!DoShadow(object, NULL, DO_SOMETHING, METHOD_END)) { retval = GetShadowError(); /* * tempV[0] is the error code. * tempV[1] is reserved at the moment, and is garbage for now. */ switch(errorCode = retval.tempV[0]) { /* * The following flags are from misc.h */ case 0: /* * No Error! */ case NO_SHADOW_PROCESS: /* * Could not retrieve an error because the current * process is not registered with SHADOW. */ case CANNOT_ALLOCATE_OBJECT: /* * SHADOW could not allocate a new object. */ case CANNOT_ALLOCATE_PROCESS: /* * The method was supposed to invoke a process to * handle it, but failed to create the process. */ case CANNOT_SEND_MESSAGE: /* * Either: * a) port is blocked. * b) no process to send to/from. * c) message could not be allocated. */ case CANNOT_FIND_METHOD: /* * Could not find a method to send to! */ default: } } } INPUTS <none> OUTPUTS double result; - low 32bits (d0) are the error, High 32bits (d1) are the error subcode. Be careful if your compiler starts checking for a double return in the 68881 processor, instead of d0/d1!!! RESULT BUGS none known. NOTES SEE ALSO SetShadowError NAME GetTagsSize -- gets the size of a NULL terminated aray. SYNOPSIS size = GetTagsSize( tags, size ) d0 a0 d0 FUNCTION This function will find the size of a longword-NULL-terminated array. The NULL termination should be valid for the first longword of the last array element. The passed size should be the size of each array element. INPUTS void *tags; - a pointer to the array. If NULL, returns NULL long size; - the size of each element in the array. OUTPUTS long size; - the size of the array, including the NULL element. RESULT BUGS none known. NOTES SEE ALSO NAME InitOOProgram -- initialize an AmigaDOS process as a shadow process SYNOPSIS result = InitOOProgram( name ) d0 a0 FUNCTION This function will initialize the calling amigaDos process as a SHADOW process. This means that tc_UserData is HANDS OFF from that point on ('cept for read only). The process object is stored in tc_UserData and all message ports, etc. are allocated. This function MUST be called before initiating any non-CALL methods. Any methods that would require a SYNC or an ASYNC message require that a process object exist in tc_UserData of the calling task. If you want to use something other than PROCESS_CLASS, then you may first set FindTask(NULL)->tc_UserData to NULL, then call METH_SUB on the process class, then send that class a METH_CREATE, then send the object that that returns a METH_ASSOCIATE. That's all this function does.... [Excepting the METH_SUB call, of course....] Please be sure NOT to use the object that is returned (that is, do NOT DropObject() the returned process object!!!!) There is an example of this sans the mETH_SUB call in ShadowLibraryMethods.doc under the METH_PROC_ASSOCIATE method description. INPUTS char *name; - the name to give the process object. The name defaults to FindTask(NULL)->tc_Node.ln_Name when passed in as NULL. OUTPUTS BOOL result; - result code The result code is a boolean describing success or failure of process object creation. FALSE (0) is an error. RESULT Process object is created for the calling task. BUGS none known. NOTES tc_UserData is trashed (used) SEE ALSO RemoveCurrentProgram() NAME InitTable -- Initializes a memory table. SYNOPSIS result = InitTable( list, allocfunc, freefunc, size ) d0 a0 a1 d0 d1 FUNCTION Shadow requires a number of very small elements to be coninually allocated and freed. This function initializes a struct MemoryList which attempts to ease the strain on AllocMem and FreeMem by allocating and freeing blocks that are 32 times "size". The individual elements are allocated via the AllocateItem() and FreeItem() functions. InitTable initializes the various parts of the passed MemoryList structure. INPUTS SEMLIST list; - a MemoryList to initialize. TABLENODE allocfunc(SEMLIST); - an allocation function that, given a d0 a0 MemoryList, returns a MemoryNode structure as a header to 32 elements to be doled out by AllocateItem(). If passed as NULL, the system uses an internal routine. void freefunc(SEMLIST, TABLENODE); a0 a1 - a free function that, given a MemoryList and a MemoryNode, frees the Node plus the 32 elements from the List. If passed as NULL, the system uses an internal routine. long size - the size of each element. OUTPUTS BOOL result; - result code The result code is a boolean indicating the success or failure of the function call. A zero value indicates that an error occured. RESULT The specified list is initilized, the first 32 elements are allocated, the semaphore is initialized, the memlst_semUse flag in the structure is set to TRUE, and the memlst_size set to the passed size. BUGS none known. NOTES It's not very flexible, but it's used for BinNodes, semaphores, list, and MethInvokeSpec internal structures. It's got pretty good, but not fantastic, performance. See "PerfTest MEMORY" results. SEE ALSO AllocateItem() FreeItem() FreeTable() NAME InitThread -- initializes the process object associated with the task. SYNOPSIS task = InitThread( task ) d0 a0 FUNCTION This function is no longer valid under SHADOW V. If you have been calling it and need directions on how to update your software, please see both the ShadowLibraryMethods.doc and the Introduction.doc about the PROCESS_CLASS. NOTES SUPERCEDED! NAME InsertSuperClass -- Take known class and insert another superclass level SYNOPSIS InsertSuperClass( subClass, newSuperClass ) a0 a1 FUNCTION This function is useful for adding methods to a Class. Unfortunately, it is currently impossible to remove these same methods once added, so be very careful with what you're doing here! Basically, this function takes the old superclass and makes the newSuperClass the old subclass' superclass. This function also flushes the entire method cache as it assumes that some method cache lines might be incorrect. INPUTS META subClass; - the subclass whose superclass will be changed. If NULL, no harm will come. META newSuperClass; - the new superClass for the passed subClass if NULL, the old superClass will remain. OUTPUTS <none> RESULT BUGS none known. NOTES The newSuperClass is "swallowed" by this function. if you want to keep the newSuperClass pointer valid within your sequence of execution after this call, you will need to do something like: InsertSuperClass(old, UseObject(new)); This function is only valid if the new superclass is, itself, a subclass of the old subclass' superclass. IE: Class A | /\ / \ Class B Class C \ \ Class D It is valid to make Class B's new superclass either Class C or Class D. However, Class D cannot have its superclass reset to class B. No class may be its own superclass! Such a class would never go away! You may NOT add any new attributes with this call. That is, the newSuperClass must not have any new attributes not located in the oldSubClass. In addition, if you define default values for the existing attributes, these default attributes will NOT propagate down to the oldSubClass. This function is meant to add METHODS ONLY! Do not attempt to use it for anything else or you will be burnt. SEE ALSO UseObject() DropObject() CreateMeta() NAME InvalidateCache -- invalidates cache entries SYNOPSIS InvalidateCache( class, selector ) a0 FUNCTION This function will invalidate all entries in the method's cache that refer to the passed class and/or the passed selector. If passed a NULL class, then every entry in the cache that contains a selector field that matches the address of the passed selector is cleared. You should call this whenever you create a selector on the stack, or in memory, and then free the associated memory. If passed a NULL selector, then every entry in the cache that contains a class field that matches the address of passed class is cleared. You should call this whenever a class is free'd. if both fields are NULL, then the entire cache is flushed. This is called whenever a program exits from memory. That's because there are many methods which become invalid at that point, but invalidating all of them would be tedious, so the entire cache is flushed. Notice that that's with every PROGRAM, NOT every PROCESS. If both fields are passed in as non-NULL, then cache entries are only freed for those entries that match both the class and the selector. However, I haven't found a good use for this case. Perhaps you folks can? INPUTS META *class; - a class. char *selector; - a method selector OUTPUTS RESULT No more references to a defunct class exists in the method calling cache. No more references to the defunct selectors exists in the method calling cache. BUGS none known. NOTES SEE ALSO DSM() DoShadow() SetMethodArgs() AddMethods() DestroyMethodTable() FindMethodHandle() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME IpcItemTransfer -- Transfers a resource from message to server. SYNOPSIS IpcItemTransfer( msg, num ) a0 d0 FUNCTION This function will transfer the resource found in the num'th item in msg to the calling server. Basically, the IPC_ITEM_TRANSFER flag is cleared, and the IPC_SERVER_OWNED flag is set. This is very important to do when inside of a METH_DESTROY method. You need to transfer the passed object out of the message! INPUTS struct IPCMessage *msg; - the (possibly NULL) message to xfer resources from. If msg is NULL, no action is taken. long num; - the item number where the resource is currently located. OUTPUTS none RESULT resource is no longer valid in the message. BUGS none known. NOTES SEE ALSO IpcARGTransfer() macro ppipc.library documentation. Not included in SHADOW, but available on a Fred Fish disk. NAME JunkIPCMessage -- Frees a message allocated by MessageMaker SYNOPSIS JunkIPCMessage( msg ) a0 FUNCTION This function will delete an IPCMessage, releasing all resources which have not been IpcItemTransfer()'d. The message itself is also deleted. Message should have been allocated by MessageMaker, although that is not the only legal case, it is the safest route to compatibility. The PreParseShadow() function calls the MessageMaker() internally. INPUTS struct IPCMessage *msg; - the message to delete. If NULL, no action is taken. OUTPUTS none RESULT One more message is gone. BUGS none known. NOTES SEE ALSO MessageMaker() IpcItemTransfer() NAME MessageMaker -- Creates a Message for the given MethodHandle & args. SYNOPSIS msg = MessageMaker( handle, args ) d0 a0 a1 FUNCTION This function will create a ppipc message that MessageParse() and ParseShadowMessage() can unroll in order to call a method asynchronously across tasks. Full resource tracking is done, and all resources are freed during the JunkIPCMessage() call, unless an IpcItemTransfer() was performed for that resource's item. IpcItemTransfer should be done during METH_DESTROY. INPUTS struct MethodHandle *handle; - the method that the message should serve. Set the low bit of the address if this is actually a ptr into a MethodHandle object as returned from PatcherClass INIT. void **args; - the arguments that should be placed, one by one, into the message structure. Full resource tracking will be done for these arguments according to the ArgumentTag structure, so the message can be sent asynchronously. OUTPUTS struct IPCMessage *msg; - The returned message. RESULT A new message is constructed. BUGS none known. NOTES SEE ALSO JunkIPCMessage() DropObject() SetMethodArgs() ParseShadowMessage() MessageParse() NAME MessageParse -- Parses a message onto the stack. SYNOPSIS value = MessageParse( msg ) d0 a0 FUNCTION This function will parse a message onto the stack according to the ArgumentTag structure as passed inside of the message. The message must have exactly the right number of items, or bad things may happen. The Method is then called, and its return value returned in d0. There is also some magic which allows DSM() to be called as the function, so that methods which are forced ASYNC by the flags in an original DSM() call, actually work properly.... INPUTS struct IPCMessage *msg; - should be a valid message set up by MessageMaker(). OUTPUTS void *value; - the return value of the method call. RESULT The METHOD is called. BUGS none known. NOTES SEE ALSO MethodFuncParse() DSM() MessageMaker() NAME MethodFuncParse -- Copies the stack arguments back to the stack. SYNOPSIS return = MethodFuncParse( object, class, args, handle, flags ) d0/d1 d0 d1 a1 a2 d7 FUNCTION This function will copy the arguments found in args onto the stack, according to the ArgumentTag structure found in handle. Unlike MessageParse(), it must deal with missing arguments -- ie: it may encounter METHOD_END (0x80000001) before the end of the ArgumentTag argument array. The missing arguments are NULL'd out, then it calls the method function, and returns d0/d1 as a double. D0 is what should normally be considered as the return value. DSM() is incapable of returning real doubles at the current time. D1 is used by DSM() for its METH_FLAG_CHECK_CONTINUE. ParseShadowMessage() has some magic for storing D1 away for synchronous method calls. The 'msg' parameter of all Methods is NULL'd by MethodFuncParse(). INPUTS OBJECT object; - the object being called. META *class; - the class the method is defined in. void **args; - the (other) arguments to the function. struct MethodHandler *handle;- the method's handle ULONG flags; - set this field to zero for now. This field reserved by system for future expansion and current asynchronous magic. OUTPUTS double return; - the return value is usually considered D0, but D1 is used by DSM() for its _CONTINUE checking. RESULT The METHOD was called. BUGS none known. NOTES SEE ALSO MessageParse() DSM() ParseShadowMessage() NAME ParseShadowMessage -- parses the three types of SHADOW messages SYNOPSIS return = ParseShadowMessage( msg, flags ) d0 a0 d0 FUNCTION This function parses the three types of messages that SHADOW programs can receive -- AMET, SMET and JAZZ. AMET message are asynchronous messages, and these message are correctly handled by MessageParse(). The message is Junk()'d via the JunkIPCMessage call. SMET messages are synchronous message and these message are correctly handled by MethodFuncParse(). The message is replied to when MethodFuncParse() is finished. JAZZ messages are message you can send. The function pointer should be in the first element of the message, and the single argument to the function should be in the second argument. No value is currently returned -- but if someone needs to, please let me know. They are currently unused. The message is returned when the function is finished. The flags override certain features of this function. There are currently three flags: SHADOW_RETURN_MSG_ALWAYS SHADOW_RETURN_MSG_NEVER SHADOW_RETURN_MSG_ON_FAILURE By default (SHADOW_MSG_RETURN_NEVER), messages are always swallowed by this function. If you wish the message to neither be replied to or Junk()d via the JunkIPCMessage() call, call the function with the SHADOW_RETURN_MSG_ALWAYS. The msg will then be returned to you for whatver further processing you wish.... If you don't know whether this is a SHADOW message or not, you can call the function with the SHADOW_RETURN_MSG_ON_FAILURE. If the message is not an AMET, SMET or JAZZ message, the msg will be returned to you for further processing. Note, however, that the assumption is that the message -is- a struct IPCMessage, and not some other form of message (like struct IntuiMessage, for instance). You have been warned. For the default behaviour, pass in the SHADOW_RETURN_MSG_NEVER flag. This was the old behaviour of ParseJazzMessage() under SHADOW 4. INPUTS struct IPCMessage *msg; - a message sent to a SHADOW task's port. ULONG flags; - one of three flags. OUTPUTS struct IPCMessage *return; - exact return is dependent on the flags passed into ParseShadowMessage(). RESULT The correct function is called. BUGS Does not handle unknown messages without replyports properly under the SHADOW_RETURN_MSG_NEVER mode. So don't send them! NOTES SEE ALSO MessageParse() MethodFuncParse() NAME PrepareAttrTags -- Prepares Attribute tags for class definition SYNOPSIS num = PrepareAttrTags( tags, countptr, super ) d0 a0 d1 a1 FUNCTION This function is designed specifically because of the inherent trickiness of Metas. Under normal situations, the functionality of this function would be incorporated into AddAttributes(). Unfortunately, because Metas are their own classes, the size of the Meta depends on the definitions held in the defining AttributeTags. Therefore, the Meta cannot be allocated until it knows the required size, it wouldn't know the size until the AddAttributes call, but it can't call AddAttributes until the Meta exists so that the AttributeTable pointer can be passed in. At anyrate, this function determines the number of new attribute there are (returned num) and the additional size that will be needed (by incrementing the *countptr for each new attribute). Attributes which are already contained within the super are cheerfully ignored. Respecified Attributes are assumed to be attempts to redefine the default value, not to respecify an attribute's size. You probably won't need to use this function, unless you are creating your own Meta or METHODs for Metas. INPUTS ATTRIBUTE_TAG tags[]; - optional pointer to a NULL terminated array of AttributeTags. long *countptr; - initialized pointer to the long which will be incremented by the additional size required by the passed attributes. If any attributes are redefined (from the super), the size will not be incremented for that attribute. META *super; - optional pointer to a superclass. OUTPUTS long num; - number of new attributes (does not include attributes redefined from the passed super. RESULT The countptr variable is incremented by the additional size, above and beyond the size of 'super', that the passed attribute tags would require. BUGS none known. NOTES *countptr MUST be initialized, probably to the size of the superClass, as the size of the superClass is not used in calculating the size (*countPtr) in this function. SEE ALSO AddAttributes() CopyDefaultAttributes() FreeAttributes() FindAttribute() FindAttrDefn() NAME PSem -- procures the semaphore for the given address. SYNOPSIS result = PSem( address, flags ) d0 a0 d0 FUNCTION Copious documentation on the PSem() function is provided for in the Introduction.doc. Please see it if this AutoDoc does not answer your questions.... This function semaphores the given address dictated by the following flags: SSEM_READ SSEM_ATTEMPT SSEM_WRITE SSEM_LOCK (SSEM_READ | SSEM_WRITE) In addition, several other flags alter the semaphoring code: SSEM_VARIABLE 0x8 SSEM_MAX 0x10 SSEM_SUBTRACT 0x80000000 SSEM_DESTROY 0x20 The following macros have been built around PSem() to add readability: /* * Conditional variables */ SetCondition(address,number)\ PSem(address, SSEM_VARIABLE | SSEM_READ | ((-number) << 8)) WaitCondition(address,number)\ PSem(address, SSEM_VARIABLE | SSEM_READ | (number << 8)) CreateCondition() PSem((void *)-1, SSEM_VARIABLE) DestroyCondition(address)\ PSem(address, SSEM_VARIABLE | SSEM_DESTROY) /* * Level-triggered semaphores. */ WaitLevel(address)\ PSem(address, SSEM_ATTEMPT|SSEM_WRITE);\ PSem(address, SSEM_READ);\ VSem(address) SetLevel(address)\ VSem(address); /* * "Sticky" semaphores */ CreateSemaphore(count) PSem((void *)-1, SSEM_MAX | (count << 8)) DestroySemaphore(address) PSem(address, SSEM_DESTROY) /* * Couting semaphores of various kinds. */ ObtainNumber(address,num) PSem(address, SSEM_READ | (num << 8)) ReleaseNumber(address, num) PSem(address, SSEM_READ | ((-num) << 8)) UpCountSem(address,max) PSem(address, SSEM_READ | SSEM_MAX |\ (max << 8)) DownCountSem(address) VSem(address) /* * Locks */ WriteLock(address) PSem(address, SSEM_WRITE) ReadLock(address) PSem(address, SSEM_READ) RWLock(address) PSem(address, SSEM_READ | SSEM_WRITE) If anyone else attempts to semaphore the same address (via PSem), the system takes appropriate action (according to the flags). if the system cannot allocate a sempahore object internally, a busy loop with a Delay(30) is used until it can. You are guaranteed that, when PSem returns, you have a lock o the semaphore -- unless SSEM_ATTEMPT is used, in which case you must look at the return code. INPUTS void *address; - Any address within the system. (-1) is reserved as allocating a new semaphore -- that semaphore address would be returned.... ULONG flags; - some combination of the flags above. OUTPUTS void *result; - result code for SSEM_ATTEMPT. Otherwise, returns semaphore address. This will be equivalent to the argument "address", or the allocated semaphore address if "address" is (-1). The result code for SSEM_ATTEMPT is (1L) for success and NULL for failure. RESULT The specified semaphore action will have taken place. BUGS none known. NOTES Although it is not strictly necessary, you will undoutedly encounter bugs if the address on which you have a semaphore is freed before the semaphore is. Mostly because another task may then allocate that address, and attempt a semaphore on it -- leading to unexpected deadly embrace conditions. The address passed need not point to an object, as the BinTree and List code require. SEE ALSO From exec.library: ObtainSemaphore() ObtainSemaphoreShared() AttemptSemaphore() VSem() Introduction.doc NAME PSemString -- used to ensure single-thread startup. SYNOPSIS result = PSemString( char *string, long semFlags ) a0 d0 FUNCTION Does the following: return PSem(UseString(string), semFlags); The browser uses this function to ensure that only a single copy of itself is running. INPUTS char *string; - the system string equivalent which is used to semaphore thread startup. long semFlags; - the flags to send to PSem(). OUTPUTS void *result; - result code for SSEM_ATTEMPT. Otherwise, returns semaphore address. This will be equivalent to the argument "address", or the allocated semaphore address if "address" is (-1). The result code for SSEM_ATTEMPT is (1L) for success and NULL for failure. RESULT BUGS none known. NOTES SEE ALSO VSemString() PSem() VSem() NAME QuickDropString -- Decrements the useCount of a known system string. SYNOPSIS QuickDropString( string ) a2 FUNCTION This function decrements the useCount of a known system string. The passed string *must* be a pointer to a system string. If the useCount drops to zero, DropString is automatically called in order to delete the string object from the correct place in the system's string hash table. Therefore, only call QuickDropString when you think you will have more than one reference to them. That allows QDS() to work fastest. INPUTS char *string; - the string to lower the refcounts of the system string. OUTPUTS RESULT The given system string has had its useCount decremented. BUGS none known. NOTES SEE ALSO UseString() QuickUseString() FindString() DropString() NAME QuickUseString -- Increment the usage counter of a system string. SYNOPSIS string = QuickUseString( string ) d0 a2 FUNCTION This function increments the system usage counter for a string that you already know is a system string. This must be the *address* of the system string, not a buffer pointer equivalent. If you pass in a NULL, this function returns a NULL. You should UseString() whenever saving a suitable string into a structure -- a matching DropString() will then deallocate the reference. Under the appropriate conditions (mentioned above) you may use QuickUseString() to avoid the hash and binary search calls. INPUTS char *string; - the system string whose useCount should be incremented OUTPUTS char *string; - the system string. Exactly what was passed into it! RESULT The system string's internal useCount is incremented BUGS none known. NOTES Don't pass in arbitrary buffer pointers or you may risk overwriting your stack, or memory. SEE ALSO UseString() FindString() DropString() QuickDropString() NAME RecurseTree -- Recursively call a function on each BinNode of an AVLTREE SYNOPSIS result = RecurseTree( bt, func, data, recurse ) d0 a0 a1 d0 d1 FUNCTION This function will recurse through the binary tree, calling func() for each object found with the parameters 'object key data', where object is the object in the binary tree, key is the key that the object is sorted on, and data is the data passed into the Recurse() call. If this func() ever returns non-NULL, the recursion is stopped, and the non_NULL return code is returned to the caller of RecurseTree. There are three different ways to recurse through a binary tree. The following flags are defined in shadow/bintree.h: SHADOW_RECURSE_INORDER == 1 SHADOW_RECURSE_PREORDER == 2 SHADOW_RECURSE_POSTORDER == 3 SHADOW_RECURSE_BACKORDER == 4 The order of the recursion is determined by these flags passed as the recurse parameter. INORDER outputs the left children, then the root, then the right children. PREORDER outputs the root, the left, then the right. POSTORDER outputs the left, the right, then the root. BACKORDER outputs the right, the root, then the left. INPUTS AVLTREE *bt; - the binary tree to recurse over. void *(*func)(void *, ULONG, void *) - the function. return value a0 d0 a1 used below. Return NULL to continue recursive calling, non-NULL to end recursive calls. Three parameters are: object, key, data. See above. void *data - the passed data long recurse - the recurse type flag. OUTPUTS void *result; - returns non-NULL result of func() if func() ever returns non-NULL. Else returns NULL. RESULT func() called for each element in the binary tree. BUGS None known. NOTES Do NOT RemoveTreeNode() the object from the binary tree that you are recursing through in the passed function. AND do not call any methods that would.... Remember that the keys are sorted unsigned, not signed. SEE ALSO AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() RemoveWatchedTreeNode() FreeTreeAllNodes() RemoveWatchedTreeStringNode() RemoveTreeNode() RemoveTreeStringNode() NAME RemoveAllPatches -- Removes all Patches from a given class. SYNOPSIS RemoveAllPatches( meta ) a0 FUNCTION This function will remove all of the method patches of a given class. This should be executed when deleting a class in which methods could be patched. It is currently called in the META_DESTROY of the metaclass and the metaCluster. Because of this, it is IMPOSSIBLE to patch the METH_DESTROY method for any metas, because they are their own classes -- the function that would call RemoveALlPatches may be in a method-chain, which would not be valid when control returned to DSM() to continue the method chain. This would be confusing, at best.... :( INPUTS META meta; - the class to delete all the patches from. OUTPUTS RESULT BUGS none known. NOTES SEE ALSO DSM() DoShadow() InvalidateCache() SetMethodArgs() AddMethods() DestroyMethodTable() FindMethodHandle() BlockMethod() SetupMethodTags() NAME RemoveAutoResource -- Removes resource from process' tracking tree. SYNOPSIS resource = RemoveAutoResource( task, resource, key ) d0 a0 d0 a1 FUNCTION The resource, which is found using the resource/key pair, is removed from the process' ATTR_RESOURCETREE and returned back to your control. No METH_REMOVE is done, and you must DropObject() the resource which is returned. Task parameter is optional and defaults to the current task. Resource parameter is optional, and defaults to whatever resource is found using the provided key. (If key >255, then key is assumed to be a string, and is handled accordingly.) INPUTS OBJECT task; - The optional task object that performs the auto-tracking. If not specified, assumes current taskObject. OBJECT resource; - The optional object being auto-tracked. If no resource, then resource is looked up on the binary tree using the value in key. char *key; - The name of the resource. Resources without names are stored by their addresses. Name addresses of 0-255 are reserved for priority freeing. Resources are freed in INCREASING key order. OUTPUTS OBJECT resource; - The resource as found. You must DropObject() the returned resource when you are no longer interested in it. Eventually, you must RemoveObject() the resource when the resource is no longer needed -anywhere-! RESULT BUGS none known. NOTES SEE ALSO AddAutoResource() DropObject() NAME RemoveClassWatcher -- Removes a watcher from all classes. SYNOPSIS RemoveClassWatcher( watchName, director, name, class ) a0 a1 d0 d1 FUNCTION This function will remove the director from the class' attribute watching SList of the passed name. This is a low-level routine. You should call the DIRECTOR_CLASS routines instead. See browser.c, or ShadowLibraryMethods.doc. INPUTS char *watchName; - the attribute name that is watched OBJECT director; - the director to Remove from the attribute watching SList. char *name; - the name of the watcher. META class; - the class to remove the watcher from. OUTPUTS none RESULT The director is removed from the class' watch list. BUGS none known. NOTES SEE ALSO AddWatcherNode() RemoveWatcherNode() AddClassWatcher() NAME RemoveCurrentProgram -- removes the current process from the system. SYNOPSIS RemoveCurrentProgram( semaphore ) a0 FUNCTION This function is the counterpart of InitOOProgram(). It removes an AmigaDOS loaded program from the system so that that program can exit safely. This is S.O.P. for cleaning up a -program-. RemoveCurrentProgram() waits for no other process to own a reference to the process associated with the program. While it does this, it handles messages on jp_port and jp_replyPort (struct ShadowProcess). This function sends a METH_REMOVE to the processObject, and waits on the process' jp_port and jp->replyPort for messages (which it manages by taking everything off the list, handling the messages, then checking for more signals). It also waits for a ^C and then checks that jp_parent is NULL. A program may create many threads on itself. When INIT'ing a process object, one parameter that the programmer can pass is a SEMF. This is a pointer to a semaphore that is passed into the process creation code. It is ObtainShared() during the process startup, and Release()'d when the thread is done executing. RemoveCurrentProgram() waits on this semaphore until all threads have exited before removing the program's process object. A NULL semaphore is dealt with appropriately. INPUTS struct SignalSemaphore *semaphore; - the thread semaphore OUTPUTS RESULT The program's process object is removed and associated ports freed. BUGS none known. NOTES SEE ALSO InitOOProgram() NAME RemoveObject -- send a METH_REMOVE to an object. SYNOPSIS RemoveObject( OBJECT object ) a0 FUNCTION Does a: DoShadow(object, NULL, METH_REMOVE, METHOD_END); Followed by a: DropObject(object); This removes the object from the system lists, and from your local sequence of execution. You should not refer to "object" after you pass it into this function unless you have maintained an additional usage of the object as in: RemoveObject(UseObject(object); /* * I can still use object! */ . . . DropObject(object); INPUTS OBJECT object; - the object to send the Remove method to. OUTPUTS none. RESULT BUGS none known. NOTES SEE ALSO CreateInstance() -- in ShadowLibFuncs.doc CreateSubClass() -- in ShadowLibFuncs.doc NAME RemoveSListNode -- removes a node from a prioritized, singly-linked list. SYNOPSIS result = RemoveSListNode( list, object, name ) d0 a0 a1 d1 FUNCTION This function removes an object from a singly linked list with the given name. INPUTS SList *list; - a pointer to the list from which to remove the object. OBJECT object; - the object to remove. char *name; - the name it was added as. OUTPUTS BOOL result; - result code returns FALSE if can't find the node to Remove. RESULT One fewer nodes are on the list. BUGS none known. NOTES SEE ALSO FindNodePriInSList() AddWatchedSListNode() AddSListNode() RemoveWatchedSListNode() NAME RemoveThread -- removes a previously initialized thread. SYNOPSIS RemoveThread( object ) a0 FUNCTION This function is no longer valid under SHADOW V. If you have been calling it and need directions on how to update your software, please see both the ShadowLibraryMethods.doc and the Introduction.doc about the PROCESS_CLASS. NAME RemoveTreeNode -- Removes a node from a binary tree SYNOPSIS result = RemoveTreeNode( bt, object, key ) d0 a0 a1 d0 FUNCTION This function will remove an object from the binary tree, dropping it via DropObject(). The object pointer is required to verify the correct node is being removed (in case nodes with the same key exist in the same tree). INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. OBJECT object; - the object to add into the tree. ULONG key; - the key value to insert on. OUTPUTS BOOL result returns FALSE on failure to remove. RESULT The object exists in the tree at least one fewer times than it did. BUGS none known. NOTES Remember that the keys are sorted unsigned, not signed. SEE ALSO DropObject() AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() RemoveWatchedTreeNode() FreeTreeAllNodes() RemoveWatchedTreeStringNode() RecurseTree() RemoveTreeStringNode() NAME RemoveTreeStringNode -- Removes a node from a binary tree. SYNOPSIS result = RemoveTreeStringNode( bt, object, name ) a0 a1 d1 FUNCTION This function will remove an object from the binary tree, dropping it via DropObject(), and dropping the string via DropString (if the node is found!). The object pointer is required to verify that the correct node is being removed (in case nodes with the same key exist in the same tree). INPUTS AVLTREE *bt; - a pointer to the root of the binary tree. OBJECT object; - the object to add into the tree. char *name; - the name to insert on. OUTPUTS BOOL result returns FALSE on failure to remove. RESULT The object exists in the tree at least one fewer times than it did. BUGS none known. NOTES Yes, that's d1, not d0 for 'name' parameter. SEE ALSO DropObject DropString AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() RemoveWatchedTreeNode() FreeTreeAllNodes() RemoveWatchedTreeStringNode() RecurseTree() RemoveTreeNode() NAME RemoveWatchedSListNode -- removes a node from a watched, prioritized singly-linked list. SYNOPSIS result = RemoveWatchedSListNode( list, object, name ) d0 a0 a1 d1 FUNCTION This function removes an object from a watched, singly-linked list with the given name. If any parties are interested, WatcherDispatch is called with W_REMOVE_NODE for the flag parameter. INPUTS W_SLIST list; - a pointer to the list from which to remove the object. OBJECT object; - the object to remove. char *name; - the name it was added as. OUTPUTS BOOL result; - result code returns FALSE if can't Remove. RESULT One fewer nodes are on the list. BUGS none known. NOTES SEE ALSO FindNodePriInSList() AddWatchedSListNode() AddSListNode() RemoveSListNode() NAME RemoveWatchedTreeNode -- Removes an object from the watched binary tree. SYNOPSIS result = RemoveWatchedTreeNode( bt, object, key ) d0 a0 a1 d0 FUNCTION This function will remove an object from the watched binary tree, dropping it via DropObject(). The object pointer is required to verify the correct node is being removed (in case nodes with the same key exist in the same tree). If any parties are interested, WatcherDispatch is called with W_REMOVE_NODE INPUTS W_AVLTREE *bt; - a pointer to the root of the watched binary tree. OBJECT object; - the object to add into the tree. ULONG key; - the key value to insert on. OUTPUTS BOOL result returns FALSE on failure to Remove. RESULT The object exists in the tree at least one fewer times than it did. Remember that the keys are sorted unsigned, not signed. BUGS none known. NOTES SEE ALSO DropObject() AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() FreeTreeAllNodes() RemoveWatchedTreeStringNode() RecurseTree() RemoveTreeNode() RemoveTreeStringNode() NAME RemoveWatchedTreeStringNode -- Removes an object from the given binary tree SYNOPSIS result = RemoveWatchedTreeStringNode( bt, object, name ) d0 a0 a1 d1 FUNCTION This function will remove an object from the watched binary tree, dropping it via DropObject(), and dropping the string via DropString (if node is found!). The object pointer is required to verify the correct node is being removed (in case nodes with the same key exist in the same tree). If any parties are interested, WatcherDispatch is called with W_REMOVE_NODE INPUTS W_AVLTREE *bt; - a pointer to the root of the watched binary tree. OBJECT object; - the object to add into the tree. char *name; - the name to insert on. OUTPUTS BOOL result returns FALSE on failure to remove. RESULT The object exists in the tree at least one fewer times than it did. BUGS none known. NOTES SEE ALSO DropObject DropString AddTreeNode() AddWatchedTreeNode() AddTreeStringNode() AddWatchedTreeStringNode() FindTreeNode() RemoveWatchedTreeNode() FreeTreeAllNodes() RecurseTree() RemoveTreeNode() RemoveTreeStringNode() NAME RemoveWatcherNode -- Removes a watcher to the watched variable SYNOPSIS result = RemoveWatcherNode( wv, node, name ) a0 a1 d1 FUNCTION This removes a watcher node from a watched variable. This is a low-level routine. You should call the DIRECTOR CLASS routines instead. See browser.c, or ShadowLibMethods.doc. If any parties are interested, WatcherDispatch is called with W_REMOVE_WATCHER for the flag parameter. INPUTS W_VALUE *wv; - the watched variable being watched. OBJECT node; - the director to remove from the watch list. char *name; - the name of the watcher. OUTPUTS BOOL result returns FALSE if failed to Remove. RESULT The director is removed from the watch list. BUGS none known. NOTES SEE ALSO AddWatcherNode() AddClassWatcher() RemoveClassWatcher() NAME ReplaceObject -- Semaphored access to an object in a public area. SYNOPSIS oldObject = ReplaceObject(objectPtr ,newObject, oldValue ) d0 a1 d0 d1 FUNCTION In some attributes, there may be object pointers that you need to change in that attribute. On the other hand, somebody else might retrieve it at the same time. This function uses the ShadowBase->sb_semSemaphore to protect the access to the objectPtr. The object that is returned is returned Use()'d, so when you are done with the object you should call DropObject(object) on it. The old value that was stored at the objectPtr address is returned as oldObject and replaced by newObject if, and only if, it is the same as oldValue. Otherwise newObject is returned. The newObject is TRANSFERRED to the address, so if you want to maintain a valid pointer in newObject when ReplaceObject() returns, call this function like this: oldObject = ReplaceObject(objectPtr, UseObject(newObject), old); If you don't care about the returned object, you should call the function like this: DropObject(ReplaceObject(objectPtr, newObject, old)); Note: the returned object may, in fact, be newObject, or oldValue -- be sure you know what you're doing! INPUTS OBJECT *objectPtr; - the pointer to the structure element that holds the object pointer you want. OBJECT newObject; - object to transfer into the objectPtr. OBJECT oldValue; - the object value that this function will check for before replacing with newObject. OUTPUTS void *object; - either the same as oldValue or, newObject if *objectPtr doesn't point to oldValue. RESULT BUGS none known. NOTES SEE ALSO GetObject() SetObject() NAME SetMethodArgs -- parses a ArgumentTag structure for method creation. SYNOPSIS SetMethodArgs( mh, args ) a0 a1 FUNCTION This is a system function, you should not need to call it. However, it does serve to elucidate several issues wrt ARGUMENT_TAG structures. This function parses out the ArgumentTag structure. It sets up the mh_num, mh_size and mh_args field in the passed MethodHandle structure. If the function returns a variable that needs to be kept track of, the last ArgumentTag structure (whose at_tag should be zero) in the array should contain information for async. method sends to safely deallocate or otherwise resource track the returned value. Valid returns are: SHADOW_RETURN_BLANK 0 SHADOW_RETURN_OBJECT 1 SHADOW_RETURN_STRING 2 SHADOW_RETURN_PORT 3 SHADOW_RETURN_TAGL 4 SHADOW_RETURN_PTR 5 SHADOW_RETURN_MRFO 6 These values should be stored in the at_size field of the last ArgumentTag array item.. For SHADOW_RETURN_PTR, the size of the pointer should be stored in the at_flags field of the same item, for SHADOW_RETURN_TAGL, the size of each array item should be stored in the at_flags field of this last item, and for SHADOW_RETURN_MRFO, the offset of the returned data from the object in question should be placed in the at_flags field Normally, the system supports a number of at_tag values: 'MRFO': used for object values which add at_flags to the passed object pointer. at_size should be four at_flags -- the offset of the passed data from the object ptr. Note that MRFO exists for system use, however you are free to use the item as well -- but it's of little to no use, just pass the object instead! 'JOBJ': Used for an object. at_size should be four at_flags should be one of: SHADOW_OBJECT SHADOW_CLASSLESSOBJECT SHADOW_META SHADOW_CLASS, SHADOW_CLUSTER SHADOW_COMPOSITE though this is more for peace of mind than necessity. 'JMSG': Used for a message creted by MessageMaker() at_size should be four at_flags should be zero 'JSTR': Used for a system string. at_size should be four at_flags should be zero 'PORT': Used for a ppipc port. at_size should be four at_flags should be ???? <-- anything you like! 'TAGL': Used for a NULL terminated array. at_size should be four. at_flags should be the size of each array item 'RTRN': reserved by the system, don't use. 'APTR' a pointer to some memory. at_size should be four. at_flags should be zero if you don't want to copy the data to another block when sending async., or should be the size of the data pointed to if you do. Create you own 4 character constant: at_size should be an even number -- you can pass arbitrarily large structures on the stack, this way. at_flags ignored. INPUTS struct MethodHandle *mh; - a MethodHandle being initialized. ARGUMENT_TAG args[]; - the (optional, and NULL-terminated) ArgumentTag array for this handle. OUTPUTS RESULT mh->mh_args, mh->mh_num, mh->mh_size fields are set up properly. BUGS none known. NOTES SEE ALSO DSM() DoShadow() InvalidateCache() AddMethods() DestroyMethodTable() FindMethodHandle() BlockMethod() RemoveAllPatches() SetupMethodTags() NAME SetObject -- Semaphored access to an object in a public area. SYNOPSIS oldObject = SetObject(objectPtr , newObject ) d0 a1 d1 FUNCTION In some attributes, there may be object pointers that you need to change in that attribute. On the other hand, somebody else might retrieve it at the same time. This function uses the ShadowBase->sb_semSemaphore to protect the access to the objectPtr. The object that is returned is returned Use()'d, so when you are done with the object you should call DropObject(object) on it. The old value that was stored at the objectPtr address is returned as oldObject and replaced by newObject. The newObject is TRANSFERRED to the address, so if you want to maintain a valid pointer in newObject when SetObject() returns, call this function like this: oldObject = SetObject(objectPtr, UseObject(newObject)); If you don't care about the returned object, you should call the function like this: DropObject(SetObject(objectPtr, newObject)); INPUTS OBJECT *objectPtr; - the pointer to the structure element that holds the object pointer you want. OBJECT newObject; - object to transfer into the objectPtr. OUTPUTS void *object; - the object that *objectPtr points to. RESULT BUGS none known. NOTES SEE ALSO GetObject() ReplaceObject(); NAME SetShadowError -- Sets an error code for SHADOW SYNOPSIS SetShadowError(error, sub_error) d0 d1 FUNCTION This function sets the last SHADOW error and suberror that occurred within the calling process' context to the passed values. INPUTS error ; - the error code to set. sub_error ; - the sub-error code to set. OUTPUTS <none> RESULT BUGS none known. NOTES SEE ALSO GetShadowError NAME SetupMethodTags -- defines all methods in the MethodTag array as being run by a certain process object, and being owned by a certain object. SYNOPSIS SetupMethodTags( tags, procObject, defnObject ) a1 d0 d1 FUNCTION This function will initialize the (required, NULL-terminated) tags array so that each method is located in a particular defnObject and wants to be called in a partiular procObject's process. For instance, gui methods may exist in a libraryObject (ie: a library) and want to be run by the guiProcObject. If passed objects of -1, the current task object is used. [That is; FindTask(NULL)->tc_UserData -- CurrentProcess()] If any element within the METHOD_TAG has a defnObject already set (non-NULL), then the defnObject for that element remains as before. Similarly for the procObject field. INPUTS METHOD_TAG tags[]; - NULL-terminated MethodTag array. OBJECT procObject; - the process object in which to run the methods. OBJECT defnObject; - the object that "contains" the definition of the ArgumentTag -and- the function code. OUTPUTS RESULT BUGS none known. NOTES This is what guarantees that the function and ArgumentTag pointers remain valid as long as a method could call that function. The ArgumentTag structure is NOT copied when stored into the MethodHandler structure (the information in MethodTags and AttributeTags is). This function does not produce valid results for methods that are defined as METH_FLAG_CLASS or METH_FLAG_PORT or METH_FLAG_SPEC. You will have to fill in the procObject field for these method-types yourself. SetupMethodTags() only affects procObject and defnObject fields that are NULL. SEE ALSO DSM() DoShadow() InvalidateCache() SetMethodArgs() AddMethods() DestroyMethodTable() FindMethodHandle() BlockMethod() RemoveAllPatches() NAME UseObject -- resource tracking for shadow objects. SYNOPSIS object = UseObject( object ) d0 a0 FUNCTION This function increments the object's cob_useCount field. You should Use an object whenever you save a pointer into a structure. INPUTS OBJECT object; - the object to effect the change upon. If NULL, nothing happens OUTPUTS OBJECT object; - the same as the object sent in. RESULT object's cob_object is incremented. BUGS none known. NOTES SEE ALSO DropObject() NAME UseString -- gets a system-wide address for a given string. SYNOPSIS string = UseString( buffer ) d0 a2 FUNCTION Shadow uses a system very much similar to the NeXT's -- a system- wide repository for statis-string addresses. Strings are hashed into a 1024 table entry and chained onto sorted binary trees. The string which is returned is guaranteed to be a unique string address for the passed buffer. The passed buffer's address is *NOT* used as the system string address, so it can be a temporary stack-allocated buffer. The system string is created when a first UseString() is called for a given buffer. On the second UseString() call for the same buffer, the same string address will be returned, and an internal counter which tracks the string usage is incremented. These system strings may *NOT* be mangled, they are read-only. They are particularly good for static data that you wish to do searches on, as system-strings have a unique address, strcmp() is unnecessary, merely compare the string addresses. They are used internally for BinNode strings, method names, attribute names, class names, etc. INPUTS char *buffer; - the string to retrieve a unique system pointer for. Given a NULL input, will return NULL. OUTPUTS char *string; - the unique string as returned by the system. A NULL signals an error. RESULT Either a new system string is created, and the buffer copied into it, or an old system string is retrieved and its usage counter incremented. BUGS none known. NOTES The buffer should be word-aligned for faster access and long-word aligned for fastest access. SEE ALSO QuickUseString() FindString() DropString() QuickDropString() NAME VSem -- Vacate a semaphore SYNOPSIS VSem( address ) a0 FUNCTION This function does the equivalent of a ReleaseSemaphore on the given address. Every PSem() should be matched with a VSem(), except for PSem()s where an SSEM_ATTEMPT failed (returned NULL, in which case VSem() should NOT be called. INPUTS void *address; - Any address in the system. OUTPUTS RESULT The semaphore will be released (vacated), and the semaphore object freed if no longer needed. BUGS none known. NOTES If no semaphore with that address can be found, nothing happens. But this case may a bug in the user program as you shoudn't be freeing semaphores no one has allocated.... SEE ALSO From exec.library: ReleaseSemaphore() PSem() Introduction.doc NAME VSemString -- used to ensure single-threaded startup. SYNOPSIS VSemString( char *string ) a0 FUNCTION Does the following: VSem(FindString(string), semFlags); DropString(string); The browser uses this function to ensure that only a single copy of itself is running. INPUTS char *string; - the system string equivalent which is used to semaphore thread startup. OUTPUTS none. RESULT BUGS none known. NOTES SEE ALSO PSemString() PSem() VSem() NAME WaitThread -- synchronizes thread startup. SYNOPSIS task = WaitThread( ) d0 FUNCTION This function is no longer valid under SHADOW V. If you have been calling it and need directions on how to update your software, please see both the ShadowLibraryMethods.doc and the Introduction.doc about the PROCESS_CLASS. NAME WatcherDispatch -- Dispatches all notification methods. SYNOPSIS WatcherDispatch( flag, wv, first, second ) d0 a0 a1 d1 FUNCTION This function dispatches notification to all parties that have added themselves either to the WatchedVariable in question, or to the SList that wv->wv_firstClass points to. Watched Values are a tricky subject which will require a lot more than a simple AutoDoc note to explain them. Please see examples in browser.c for now, or refer to the DIRECTOR_CLASS documentation in ShadowLibMethods.doc and Introduction.doc. INPUTS long flag; - Informs of the type of change made to the value: W_CHANGE_ZERO 1 W_CHANGE_NON_ZERO 2 W_INSERT_WATCHER 40 W_REMOVE_WATCHER 24 W_INSERT_NODE 32 W_REMOVE_NODE 16 W_VALUE *wv; - the watchedValue that was changed. void *first; - the object that was added to the list/AVLTREE, or the value that the variable was changed to. void *second; - the name or key for the new node in the list/AVLTREE OUTPUTS RESULT All interested parties are informed of the change. BUGS none known. NOTES SEE ALSO AddWatcherNode() AddClassWatcher()